.. _Repository API: ############################################ Краткое описание Repository API ############################################ ******************************************* Назначение и общий функционал работы с API ******************************************* Концепция репозиториев для абстрагирования вызовов API создана в рамках работы над задачей #10448 Репозитории инжектированы в глобальный объект и могут вызываться либо через **this**, либо через **app** (в **asyncData**). Все методы репозиториев возвращают Promise. Далее, для удобства, в качестве возвращаемых типов методов используются типы, возвращаемые при разрешении Promise. Внутри репозитория доступны общие объекты приложения: **$backend**, **$store**, **$i18n**. .. note:: При использовании данного API во внешних скриптах в примерах **this** необходимо заменить на **repo** и название репозитория использовать без знака **$** **Пример**: :: let data = await $repos.schemaRepository('coordinates').list({ clauses: sites.map(site=>{ return { field:'siteid', operand:'eq', value:site['site_id'], operator:"or", } }), "fields": ["country","latitude","longitude","siteid",'street'], "offset": 0 } ) .. ******************************************* schemaRepository ******************************************* Используется для работы с данными и метаданными схем. Вызов: **this.$schemaRepository(schema)**, где **schema** может быть либо именем схемы, либо ID, в зависимости от эндпоинта. ================================================ Методы работы со схемой ================================================ * **get(id, fields)** - возвращает одну запись из схемы. Параметры: **id** - идентификатор получаемой записи; **fields** - массив имён полей, которые должны быть включены в запись. * **create(data, params)** - создаёт запись в схеме. Параметры: **data** - key-value объект с данными для создания; **params** - query-параметры для включения в URL. * **list(params)** - выбрать данные из схемы (все, либо в соответствии с переданными параметрами). Параметр: **params** - параметры запроса. Возвращает **Array**. * **listUnique(params)** - выбрать уникальные записи из схемы (т.е. сгруппированные по запрашиваемым полям). Параметр: **params** - параметры запроса, где свойство **distinct** всегда будет иметь значение **true**. * **listPage(pageSize, page, params)** - выбрать страницу данных из схемы. Параметры: **pageSize** - количество записей на странице (по умолчанию - 0); **page** - номер выбираемой страницы (по умолчанию - 0); **params** - параметры запроса. Возвращает **Object** со следующими свойствами: **data** - массив с выбранными записями; **total** - общее количество записей в схеме данных. * **update(data, params)** - обновить запись в схеме. Параметры: **data** - key-value объект с данными для обновления; **params** - query-параметры для включения в URL. * **delete(id)** - удалить запись из схемы. Параметр: **id** - идентификатор удаляемой записи * **getMetadata()** - получить мета-информацию о схеме. При вызове метода проверяется существование схемы в локальном хранилище (**store.state.app.schemas**), и если есть, то возвращается локальный объект. Если нет - то запрашивается с бэкенда и сохраняется в локальном хранилище. * **listMetadata()** - получить список мета-информации о всех схемах (вызов репозитория может осуществляться без указания схемы) * **clauses.get()** - возвращает шаблоны фильтров для схемы ================================================ Методы работы с вложениями ================================================ * **attachment(field, id).get(mimeType)** - возвращает вложение для поля **field** схемы и идентификатора записи **id**. Параметр **mimeType** - опциональный, по умолчанию - **'application/octet-stream'**. * **attachment(field, id).upload(data, params)** - загружает вложение для поля **field** схемы и идентификатора записи **id**. Парамерты: **data** - данные для загрузки; **params** - не обязательные дополнительные параметры для передачи в метод запроса. * **attachment(field, id).delete()** - удаляет вложение для поля **field** схемы и идентификатора записи **id**. ================================================================================================ Параметры вызова методов типа **list(params)** и **listPage(params)** ================================================================================================ При вызове методов API могут передаваться параметры. Параметры - объект, который может содержать не обязательные свойства: * **fieldName** {String} - поле в котором будет находится строгое соответствие значения, указанного в параметре **value**. Если **value** не указан, то и этот параметр игнорируется. * **value** {String, Array} - значение, строгое соответствие которого будет находится по полю **fieldName**. Если значение - строка, то сравнение значения поля происходит по эквивалентности строки. Если значение - массив строк, то сравнение значения поля происходит по эквивалентности любой из строк массива. Если **fieldName** не указан, то и этот параметр игнорируется. * **clauses** {Array} - дополнительные условия выборки в формате **clauses** вызовов API. Для подробностей можно обратиться к документации Clause API (см :numref:`Краткое описание Clause API`). * **fields** {Array} - список полей, которые нужно вернуть в выборке данных. * **maxRows** {Number} - максимальное количество записей в выборке. * **offset** {Number} - смещение относительно первой записи при выборке данных. * **distinct** {Boolean} - Флаг, возвращать ли только уникальные записи. **true** - для уникальных записей. По умолчанию - **false**. ================================================================================================ Примеры вызовов ================================================================================================ **this.$schemaRepository('incidents').list()** - выбрать все данные из схемы **incidents** **this.$schemaRepository('people').list({fields: ['full_name']})** - выбрать все данные из схемы **people**, при этом вернуть только поле **full_name**. **this.$schemaRepository('incidents').listPage(10, 3)** - выбрать 10 записей 3-й страницы из схемы **incidents** **this.$schemaRepository('schm001').getMetadata()** - получить мета-информацию о схеме с **id == 'schm001'** **this.$schemaRepository().listMetadata()** - получить список мета-информации о всех схемах **this.$schemaRepository('schm001').clauses.get()** - получить шаблоны фильтров для схемы с **id == 'schm001'** ******************************************* uiRepository ******************************************* Используется для работы с объектами UI. ================================================ Методы работы с UI ================================================ * **console(id)** - возвращает мета-информацию о консоли по идентификатору. Параметры: **id** - идентификатор консоли. * **form(id)** - возвращает мета-информацию о форме по идентификатору. Параметры: **id** - идентификатор формы. При вызове метода проверяется существование формы в локальном хранилище (**store.state.app.forms**), и если есть, то возвращается локальный объект. Если нет - то запрашивается с бэкенда и сохраняется в локальном хранилище. * **consoles(schemaId)** - возвращает список консолей для схемы. Параметры: **schemaId** - идентификатор схемы. * **forms(schemaId)** - возвращает список форм для схемы. Параметры: **schemaId** - идентификатор схемы. * **sidebars()** - возвращает список всех сайдбаров. * **sidebar(id)** - возвращает конкретный сайдбар. Параметры: **id** - идентификатор сайдбара. * **svg()** - возвращает список всех svg. * **dashboard.panes()** - возвращает список всех доступных инструментальных панелей * **dashboard.pane(id)** - возвращает конкретную инструментальную панель. Параметры: **id** - идентификатор панели. * **dashboard.chart(id)** - возвращает конкретную диаграмму из инструментальной панели. Параметры: **id** - идентификатор диаграммы. ================================================ Примеры вызовов ================================================ **this.$uiRepository.console('inc_con_001')** - получить мета-информацию о консоли с **id == 'inc_con_001'**. ******************************************* adminRepository ******************************************* Содержит методы доступа к эндпоинтам администрирования. ================================================ Методы администсрирования бэкенда ================================================ Здесь работает фабрика методов, поэтому, как правило, необходимый метод можно вычислить исходя из требуемого пути API. Например, для **/admin/forms/get** метод будет: **$this.$adminRepository.forms.get()**. Если путь содержит подчёркивание, то метод необходимо вызывать без подчёркивания в "camelСase" (см. примеры). В каждый метод можно передать параметр **data**. Кроме фабрики стандартных методов репозиторий содержит методы, которые отличаются от стандартных, либо созданы дополнительно для удобства работы с бэкендом. Такие методы приведены ниже. ================================================ Методы управления локализацией ================================================ * **i18n.listNames()** - запрос на получение списка существующих локалей в i18n. ================================================ Методы управления каталогом услуг ================================================ * **catalog.listGroupItems(groupId)** - запрос списка услуг для конкретной группы каталога услуг. **groupId** - ID группы, для которой необходимо запросить список услуг. ================================================================================================ Методы управления резервным копированием/восстановлением ================================================================================================ * **backup()** - возвращает данные для резервного копирования * **restore(data)** - восстанавливает данные. Параметры **data** - данные для восстановления. ================================================ Методы управления свойствами ================================================ * **properties.get()** - возвращает все свойства * **properties.get(property)** - возвращает конкретное свойство **property** * **properties.save(properties)** - сохраняет свойства, переданные в объекте **properties** * **properties.add(property, {value, isGlobal, description})** - добавляет новое свойство **property** со значением **value**, признаком глобального свойства **isGlobal** (по умолчанию - **false**) и описанием **description**. * **properties.update(property, {value, isGlobal, description})** - обновляет свойство **property** значением **value**, признаком глобального свойства **isGlobal** (по умолчанию - **false**) и описанием **description**. * **properties.delete(propety)** - удаляет свойство **property** ================================================ Примеры вызовов ================================================ **this.$adminRepository.sidebars.list()** - получить список всех сайдбаров (в режиме администратора) **this.$adminRepository.sidebars.get({id: 'sb_6'})** - получить мета-информацию о сайдбаре с **id == 'sb_06'** (в режиме администратора) **this.$adminRepository.catalog.listItems()** - Получить список элементов каталога (в режиме администратора) **this.$adminRepository.properties.add('test_prop', {value: 'test_value'})** - Добавить новое свойство **test_prop** со значением **test_value**, без описания и признаком глобального свойства **false**. ******************************************* appRepository ******************************************* Содержит методы для работы с общими объектами приложения ================================================ Методы для работы с объектами приложения ================================================ * **auth.token(auth)** - возвращает токен при успешной аутентификации. Параметр **auth** - объект с именем пользователя и паролем для аутентификации. * **i18n()** - возвращает объект с локализованными свойствами. * **enums()** - возвращает все enums. ================================================ Примеры вызовов ================================================ **this.$appRepository.auth.token({ user: 'user', password: 'der_parol' })** **this.$appRepository.i18n()** ******************************************* userRepository ******************************************* Содержит методы для работы с настройками пользователя. При определении пользователя берётся текущий пользователь из контекста. ================================================================================================ Методы для работы с настройками пользователя ================================================================================================ * **preferences.get()** - Получить настройки пользователя. * **preferences.add(prefs)** - Создать настройки пользователя. Параметр **prefs** - объект с настройками пользователя для создания. * **preferences.update(prefs)** - Обновить настройки пользователя. Параметр **prefs** - объект с настройками пользователя для обновления. * **preferences.delete()** - Удалить настройки пользователя. ******************************************* userApps ******************************************* Специальный репозиторий, используемый для работы со встроенными приложениями. ================================================ Методы работы с каталогом услуг. ================================================ * **catalog.get()** - получить данные о каталоге услуг. ================================================ Примеры вызовов ================================================ **this.$userApps.catalog.get()** - получить данные о каталоге услуг.